home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / ndbm.z / ndbm
Encoding:
Text File  |  1998-10-20  |  11.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. NNNNDDDDBBBBMMMM((((3333BBBB))))                                                              NNNNDDDDBBBBMMMM((((3333BBBB))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ndbm: dbm_open, dbm_open64, dbm_close, dbm_close64, dbm_fetch,
  10.      dbm_fetch64, dbm_store, dbm_store64, dbm_delete, dbm_delete64,
  11.      dbm_firstkey, dbm_firstkey64, dbm_nextkey, dbm_nextkey64, dbm_error,
  12.      dbm_error64, dbm_clearerr , dbm_clearerr64 - data base subroutines
  13.  
  14. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.      ####iiiinnnncccclllluuuuddddeeee <<<<nnnnddddbbbbmmmm....hhhh>>>>
  16.  
  17.      ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {{{{
  18.          vvvvooooiiiidddd ****ddddppppttttrrrr;;;;
  19.          ssssiiiizzzzeeee____tttt ddddssssiiiizzzzeeee;;;;
  20.      }}}} ddddaaaattttuuuummmm;;;;
  21.  
  22.      DDDDBBBBMMMM ****ddddbbbbmmmm____ooooppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeee,,,, iiiinnnntttt ffffllllaaaaggggssss,,,, mmmmooooddddeeee____tttt mmmmooooddddeeee))));;;;
  23.  
  24.      DDDDBBBBMMMM66664444 ****ddddbbbbmmmm____ooooppppeeeennnn66664444((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeee,,,, iiiinnnntttt ffffllllaaaaggggssss,,,, mmmmooooddddeeee____tttt mmmmooooddddeeee))));;;;
  25.  
  26.      vvvvooooiiiidddd ddddbbbbmmmm____cccclllloooosssseeee((((DDDDBBBBMMMM ****ddddbbbb))));;;;
  27.  
  28.      vvvvooooiiiidddd ddddbbbbmmmm____cccclllloooosssseeee66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb))));;;;
  29.  
  30.      ddddaaaattttuuuummmm ddddbbbbmmmm____ffffeeeettttcccchhhh((((DDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  31.  
  32.      ddddaaaattttuuuummmm ddddbbbbmmmm____ffffeeeettttcccchhhh66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  33.  
  34.      iiiinnnntttt ddddbbbbmmmm____ssssttttoooorrrreeee((((DDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm ccccoooonnnntttteeeennnntttt,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  35.  
  36.      iiiinnnntttt ddddbbbbmmmm____ssssttttoooorrrreeee66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm ccccoooonnnntttteeeennnntttt,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  37.  
  38.      iiiinnnntttt ddddbbbbmmmm____ddddeeeelllleeeetttteeee((((DDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  39.  
  40.      iiiinnnntttt ddddbbbbmmmm____ddddeeeelllleeeetttteeee66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  41.  
  42.      ddddaaaattttuuuummmm ddddbbbbmmmm____ffffiiiirrrrssssttttkkkkeeeeyyyy((((DDDDBBBBMMMM ****ddddbbbb))));;;;
  43.  
  44.      ddddaaaattttuuuummmm ddddbbbbmmmm____ffffiiiirrrrssssttttkkkkeeeeyyyy66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb))));;;;
  45.  
  46.      ddddaaaattttuuuummmm ddddbbbbmmmm____nnnneeeexxxxttttkkkkeeeeyyyy((((DDDDBBBBMMMM ****ddddbbbb))));;;;
  47.  
  48.      ddddaaaattttuuuummmm ddddbbbbmmmm____nnnneeeexxxxttttkkkkeeeeyyyy66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb))));;;;
  49.  
  50.      iiiinnnntttt ddddbbbbmmmm____eeeerrrrrrrroooorrrr((((DDDDBBBBMMMM ****ddddbbbb))));;;;
  51.  
  52.      iiiinnnntttt ddddbbbbmmmm____eeeerrrrrrrroooorrrr66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb))));;;;
  53.  
  54.      iiiinnnntttt ddddbbbbmmmm____cccclllleeeeaaaarrrreeeerrrrrrrr((((DDDDBBBBMMMM ****ddddbbbb))));;;;
  55.  
  56.      iiiinnnntttt ddddbbbbmmmm____cccclllleeeeaaaarrrreeeerrrrrrrr66664444((((DDDDBBBBMMMM66664444 ****ddddbbbb))));;;;
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. NNNNDDDDBBBBMMMM((((3333BBBB))))                                                              NNNNDDDDBBBBMMMM((((3333BBBB))))
  71.  
  72.  
  73.  
  74. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  75.      These functions maintain key/content pairs in a data base.  The nnnnddddbbbbmmmm
  76.      functions will handle very large (a billion blocks) databases and will
  77.      access a keyed item in one or two file system accesses.  The nnnnddddbbbbmmmm66664444
  78.      functions are identical to the nnnnddddbbbbmmmm routines except that they can be used
  79.      to operate on databases larger than 2 Gigabytes.  This package replaces
  80.      the earlier _d_b_m(3B) library, which managed only a single database.
  81.  
  82.      _K_e_ys and _c_o_n_t_e_n_ts are described by the _d_a_t_u_m typedef.  A _d_a_t_u_m specifies
  83.      a string of _d_s_i_z_e bytes pointed to by _d_p_t_r. Arbitrary binary data, as
  84.      well as normal ASCII strings, are allowed.  The data base is stored in
  85.      two files.  One file is a directory containing a bit map and has `.dir'
  86.      as its suffix.  The second file contains all data and has `.pag' as its
  87.      suffix.
  88.  
  89.      Before a database can be accessed, it must be opened by _d_b_m__o_p_e_n.  This
  90.      will open and/or create the files _f_i_l_e....ddddiiiirrrr and _f_i_l_e....ppppaaaagggg depending on the
  91.      flags parameter (see _o_p_e_n(2)).
  92.  
  93.      Once open, the data stored under a key is accessed by _d_b_m__f_e_t_c_h and data
  94.      is placed under a key by _d_b_m__s_t_o_r_e.  The _f_l_a_g_s field can be either
  95.      DDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT or DDDDBBBBMMMM____RRRREEEEPPPPLLLLAAAACCCCEEEE.... DDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT will only insert new entries into
  96.      the database and will not change an existing entry with the same key.
  97.      DDDDBBBBMMMM____RRRREEEEPPPPLLLLAAAACCCCEEEE will replace an existing entry if it has the same key.  A key
  98.      (and its associated contents) is deleted by _d_b_m__d_e_l_e_t_e.  A linear pass
  99.      through all keys in a database may be made, in an (apparently) random
  100.      order, by use of _d_b_m__f_i_r_s_t_k_e_y and _d_b_m__n_e_x_t_k_e_y.  _D_b_m__f_i_r_s_t_k_e_y will return
  101.      the first key in the database.  _D_b_m__n_e_x_t_k_e_y will return the next key in
  102.      the database.  The following code will traverse the data base:
  103.  
  104.           for (key = dbm_firstkey(db);
  105.                key.dptr != NULL;
  106.                key = dbm_nextkey(db))
  107.  
  108.  
  109.      _D_b_m__e_r_r_o_r returns non-zero when an error has occurred reading or writing
  110.      the database.  _D_b_m__c_l_e_a_r_e_r_r resets the error condition on the named
  111.      database.
  112.  
  113. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  114.      All functions that return an _i_n_t indicate errors with negative values.  A
  115.      zero return indicates ok.  Routines that return a _d_a_t_u_m indicate errors
  116.      with a null (0) _d_p_t_r. If _d_b_m__s_t_o_r_e called with a _f_l_a_g_s value of
  117.      DDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT finds an existing entry with the same key it returns 1.
  118.  
  119.      Some error conditions will set _e_r_r_n_o. These are:  EEEENNNNOOOOMMMMEEEEMMMM:::: runtime memory
  120.      allocation failed; EEEEPPPPEEEERRRRMMMM:::: file permissions don't match the process
  121.      euid/egid permissions; EEEEIIIINNNNVVVVAAAALLLL:::: key+data sizes for _d_b_m__s_t_o_r_e exceed the
  122.      internal block size; EEEEFFFFBBBBIIIIGGGG:::: hash table overflow would cause the maximum
  123.      dbm file size to be exceeded.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. NNNNDDDDBBBBMMMM((((3333BBBB))))                                                              NNNNDDDDBBBBMMMM((((3333BBBB))))
  137.  
  138.  
  139.  
  140. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  141.      dbm(3B) and Berkeley db: dbopen(3)
  142.  
  143. BBBBUUUUGGGGSSSS
  144.      The `.pag' file is designed to contain holes in files.  The EFS file
  145.      system does not implement holes, so the file will frequently be
  146.      significantly larger than the actual content.
  147.  
  148.      _D_p_t_r pointers returned by these subroutines point into static storage
  149.      that is changed by subsequent calls.
  150.  
  151.      _d_b_m databases may not be portable across machines with different
  152.      alignment restrictions or different byte sexes.
  153.  
  154.      _D_p_t_r pointers returned by these subroutines point into possibly non word
  155.      aligned storage. You cannot assume that you can cast the _D_p_t_r pointer
  156.      into an arbitrary data type and dereference it.  This is a general rule
  157.      in ANSI-C rather than _d_b_m specific, but users often hit it while using
  158.      _d_b_m.
  159.  
  160.      The sum of the sizes of a key/content pair must not exceed the internal
  161.      block size minus the _d_b_m small book-keeping overhead (currently: _PBLKSIZ
  162.      - 6 = 1018 bytes).  Moreover all key/content pairs that hash together
  163.      must fit on a single block.  For a dbm-like implementation with much less
  164.      size limitations, check out ddddbbbbooooppppeeeennnn((((3333)))) (Berkeley DB).
  165.  
  166.      _D_b_m__s_t_o_r_e will return an error in the event that a disk block fills with
  167.      inseparable data.
  168.  
  169.      _D_b_m__d_e_l_e_t_e does not physically reclaim file space, although it does make
  170.      it available for reuse.
  171.  
  172.      The order of keys presented by _d_b_m__f_i_r_s_t_k_e_y and _d_b_m__n_e_x_t_k_e_y depends on a
  173.      hashing function, not on anything interesting.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.